클로드 코드 완벽 가이드 — 26장 Claude Code Action 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

26장에서 다루는 내용

• Claude Code Action 개념 — 깃허브에서 클로드 코드를 직접 사용하는 방법
• 인터렉티브 모드 vs 헤드리스 모드 — 두 가지 실행 방식의 차이와 활용
• 클로드 코드 액션 설치하기 — /install-github-app 명령어로 단계별 설치
• 워크플로 선택과 인증 — @Claude Code 태그, Code Review, API 키/구독 연동
• 실전 활용 — PR 자동 코드 리뷰, 이슈 해결 요청

전체 흐름도

[Claude Code 실행 모드]                   [Claude Code Action 설치]
    |                                          |
    v                                          v
+---------------------------+    +-----------------------------------+
| 인터렉티브 모드            |    | 01. /install-github-app 실행      |
| - 사용자와 직접 대화       |    | 02. 리포지터리 선택                |
| - 터미널에서 실시간 작업    |    | 03. GitHub App [Configure] 클릭   |
|                           |    | 04. 앱 설치 후 Enter              |
| 헤드리스 모드              |    | 05. 워크플로 선택                  |
| - 화면 없이 백엔드 실행    |    |     - @Claude Code (태그)         |
| - 배포/자동화 작업용       |    |     - Claude Code Review (자동)   |
+---------------------------+    | 06. API 키 or 구독 모델 선택      |
            |                    | 07. Authorize → PR 머지           |
            v                    | 08. PR마다 자동 코드 리뷰 시작!   |
+---------------------------+    +-----------------------------------+
| 헤드리스 모드의 대표 활용  |
| = Claude Code Action      |
| 깃허브에서 클로드 코드를   |
| 직접 사용하는 기능         |
+---------------------------+

선수 지식 체크리스트

• [ ] Git & GitHub 기본 (리포지터리, PR, 이슈 개념)
• [ ] 클로드 코드 기본 사용법 (터미널 명령어)
• [ ] GitHub Actions / Workflow 기본 개념
• [ ] API 키와 구독 모델의 차이

핵심 키워드

26-1 Claude Code Action의 개념

한 줄 요약

클로드 코드 액션은 헤드리스 모드를 활용하여 깃허브에서 PR 리뷰, 버그 수정, 이슈 해결 등을 자동으로 수행하는 기능이다.

쉬운 설명 (비유)

인터렉티브 모드 = 직접 만나서 대화하는 회의
- 내가 말하면 상대가 바로 대답
- 실시간으로 주고받기 가능

헤드리스 모드 = 이메일로 업무 요청하는 것
- 요청서를 보내면 알아서 처리
- 결과만 나중에 받아보기

Claude Code Action = 깃허브에 상주하는 AI 팀원
- PR 올리면 자동으로 코드 리뷰
- @claude 태그하면 이슈도 해결
- 24시간 일하는 가상 개발자!

실무 예제

❌ 잘못된 이해:
"클로드 코드 액션은 반드시 API 요금제가 필요하다"

✅ 올바른 이해:
"원래는 API 요금제만 지원했지만, 이제는 구독 플랜으로도
클로드 코드 액션을 사용할 수 있다"
→ 비용 최적화가 중요하면 구독 모델 사용 추천!

핵심 체크포인트

• [ ] 인터렉티브 모드와 헤드리스 모드의 차이를 설명할 수 있다
• [ ] 클로드 코드 액션이 헤드리스 모드의 활용 사례임을 이해한다
• [ ] API 키와 구독 모델 두 가지 인증 방식을 구분할 수 있다

26-2 클로드 코드 액션 설치하기

한 줄 요약

/install-github-app 명령어로 리포지터리를 선택하고, GitHub App을 설치한 뒤, 워크플로와 인증 방식을 설정하여 클로드 코드 액션을 활성화한다.

쉬운 설명 (비유)

클로드 코드 액션 설치 = 회사에 새 팀원 입사시키기

1단계: /install-github-app = 채용 공고 내기
2단계: 리포지터리 선택 = 어느 부서에 배치할지 결정
3단계: GitHub App 설치 = 신분증 발급 (Configure 버튼)
4단계: Enter 확인 = 출입증 활성화
5단계: 워크플로 선택 = 담당 업무 배정
  - @Claude Code = "불러주면 일하기"
  - Code Review = "PR 올라오면 자동 검토"
6단계: API 키/구독 선택 = 급여 체계 결정
7단계: Authorize = 최종 계약 서명

실무 예제: 설치 단계별 가이드

# 1단계: 클로드 코드에서 명령어 실행
> /install-github-app

# 2단계: 리포지터리 선택
> Use current repository: codefactory-co/k-nomad
# 또는 Enter a different repository 선택

# 3단계: 브라우저에서 GitHub App 설치
# https://github.com/apps/claude 방문
# [Configure] 버튼 → Organization 선택

# 4단계: 클로드 코드로 돌아와서 Enter

# 5단계: 워크플로 선택 (Space로 토글, Enter로 확인)
# ✓ @Claude Code — 이슈/PR에서 @claude 태그
# ✓ Claude Code Review — 새 PR 자동 리뷰

# 6단계: API 키 선택
# > Create a long-lived token with your Claude subscription (추천!)
# 또는 Enter a new API key

# 7단계: 클로드 홈페이지에서 [Authorize] 클릭
# 8단계: 자동 생성된 PR을 머지하면 설치 완료!

핵심 체크포인트

• [ ] /install-github-app 명령어로 설치를 시작할 수 있다
• [ ] 현재 리포지터리 또는 다른 리포지터리를 선택할 수 있다
• [ ] @Claude Code와 Claude Code Review 워크플로의 차이를 안다
• [ ] 구독 토큰과 API 키 중 적합한 인증 방식을 선택할 수 있다

26-3 클로드 코드 액션 실전 활용

한 줄 요약

설치가 완료되면 모든 PR에 자동 코드 리뷰가 적용되며, 이슈에 @claude를 태그하여 버그 수정이나 기능 추가를 요청할 수도 있다.

쉬운 설명 (비유)

설치 후 일어나는 일:

PR을 올리면... → 클로드 봇이 자동으로 댓글 작성!
┌──────────────────────────────────────────┐
│ PR Review: Claude Code GitHub Workflow   │
│                                          │
│ Todo List:                               │
│ □ Read and analyze workflow files        │
│ □ Review code quality and best practices │
│ □ Check for potential bugs or issues     │
│ □ Assess performance considerations      │
│ □ Evaluate security concerns             │
│ □ Provide constructive feedback          │
└──────────────────────────────────────────┘

마치 24시간 근무하는 시니어 개발자가
모든 PR을 빠짐없이 리뷰해주는 것!

실무 예제

❌ 액션 없이 개발할 때:
1. 코드 작성 → PR 올림
2. 리뷰어에게 요청 → 리뷰어 바쁘면 대기...
3. 피드백 받기까지 수시간~수일 소요
4. 간단한 버그도 직접 찾아야 함

✅ 클로드 코드 액션 사용할 때:
1. 코드 작성 → PR 올림
2. 즉시 자동 코드 리뷰 시작!
3. 코드 품질, 버그, 보안, 성능 한 번에 체크
4. 이슈에 @claude 태그하면 수정까지 자동 처리
→ 리뷰 대기 시간 제로, 코드 품질 일관성 확보!

핵심 체크포인트

• [ ] PR 생성 시 자동 코드 리뷰가 동작하는 과정을 이해한다
• [ ] 클로드 봇의 리뷰 항목(코드 품질, 버그, 보안, 성능 등)을 알고 있다
• [ ] @claude 태그로 이슈 해결을 요청할 수 있다
• [ ] 설치 과정에서 생성된 워크플로 파일의 역할을 이해한다

연습문제

문제 1: 개념 이해 (기본)

클로드 코드의 인터렉티브 모드와 헤드리스 모드의 차이점을 설명하고, 클로드 코드 액션이 어느 모드를 기반으로 하는지 서술하세요.

문제 2: 설치 절차 (중급)

클로드 코드 액션 설치 시 선택할 수 있는 두 가지 워크플로의 이름과 각각의 역할을 설명하세요. 또한 API 키 대신 구독 모델을 선택하는 것이 유리한 상황은?

문제 3: 실전 시나리오 (심화)

팀 프로젝트에서 클로드 코드 액션을 도입하려 합니다. (1) 설치 전 확인해야 할 사항, (2) 워크플로 선택 전략, (3) 도입 후 기대 효과를 각각 설명하세요.

부록 A: 용어 사전

부록 B: 비교표

인터렉티브 모드 vs 헤드리스 모드

@Claude Code vs Claude Code Review

API 키 vs 구독 모델

부록 C: 참고 자료